/*
 * Copyright (c) 2024 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef QOS_H
#define QOS_H
/**
 * @addtogroup QoS
 * @{
 *
 * @brief 提供QoS接口，包括设置、取消和查询QoS等级。
 *
 * @since 12
 */

/**
 * @file qos.h
 * @include <qos/qos.h>
 *
 * @brief 声明QoS提供的C接口。
 *
 * @syscap SystemCapability.Resourceschedule.QoS.Core
 *
 * @since 12
 */

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 描述QoS等级。
 *
 * @since 12
 */
typedef enum QoS_Level {
    /**
     * @brief 表示QoS等级为用户不可见任务。
     */
    QOS_BACKGROUND = 0,

    /**
     * @brief 表示QoS等级为后台重要任务。
     */
    QOS_UTILITY,

    /**
     * @brief 表示QoS等级为默认。
     */
    QOS_DEFAULT,

    /**
     * @brief 表示QoS等级为用户触发任务。
     */
    QOS_USER_INITIATED,

    /**
     * @brief 表示QoS等级为限时任务。
     */
    QOS_DEADLINE_REQUEST,

    /**
     * @brief 表示QoS等级为用户交互任务。
     */
    QOS_USER_INTERACTIVE,
} QoS_Level;

/**
 * @brief 为当前线程设置QoS等级。
 *
 * @param level 表示设置的QoS等级，详细信息可以查看{@link QoS_Level}。
 * @return 成功返回0，失败返回负值。
 * @see QoS_Level
 * @since 12
 */
int OH_QoS_SetThreadQoS(QoS_Level level);

/**
 * @brief 取消当前线程的QoS等级。
 *
 * @return 成功返回0，失败返回负值。
 * @see QoS_Level
 * @since 12
 */
int OH_QoS_ResetThreadQoS();

/**
 * @brief 获得当前线程的QoS等级。
 *
 * @param level 参数是输出参数，线程的QoS等级会以{@link QoS_Level}形式写入该变量。
 * @return 成功返回0，失败返回负值。
 * @see QoS_Level
 * @since 12
 */
int OH_QoS_GetThreadQoS(QoS_Level *level);

/**
 * @brief 会话句柄
 *
 * @since 20
 */
typedef unsigned int OH_QoS_GewuSession;

/**
 * @brief 无效会话句柄，用于错误返回。
 *
 * @since 20
 */
#define OH_QOS_GEWU_INVALID_SESSION_ID (static_cast<OH_QoS_GewuSession>(0xffffffffU))
/**
 * @brief 请求句柄
 *
 * @since 20
 */
typedef unsigned int OH_QoS_GewuRequest;

/**
 * @brief 无效请求句柄，用于错误返回。
 *
 * @since 20
 */
#define OH_QOS_GEWU_INVALID_REQUEST_ID (static_cast<OH_QoS_GewuRequest>(0xffffffffU))


/**
 * @brief 格物错误码。
 *
 * @since 20
 */
typedef enum {
    /**
     * @brief 成功
     */
    OH_QOS_GEWU_OK = 0,

    /**
     * @brief 权限错误
     */
    OH_QOS_GEWU_NOPERM = 201,

    /**
     * @brief 内存错误
     */
    OH_QOS_GEWU_NOMEM = 203,

    /**
     * @brief 参数错误
     */
    OH_QOS_GEWU_INVAL = 401,

    /**
     * @brief 已存在句柄
     */
    OH_QOS_GEWU_EXIST = 501,

    /**
     * @brief 找不到句柄
     */
    OH_QOS_GEWU_NOENT = 502,

    /**
     * @brief 找不到符号
     */
    OH_QOS_GEWU_NOSYS = 801,

    /**
     * @brief 其它错误
     */
    OH_QOS_GEWU_FAULT = 901,
} OH_QoS_GewuErrorCode;

typedef struct {
    /**
     * @brief 创建出来的会话句柄
     */
    OH_QoS_GewuSession session;

    /**
     * @brief 错误码
     *
     *        - 创建会话成功返回OH_QOS_GEWU_OK。
     *
     *        - 由于没有足够的内存而创建会话失败返回OH_QOS_GEWU_NOMEM。
     */
    OH_QoS_GewuErrorCode error;
} OH_QoS_GewuCreateSessionResult;

typedef struct {
    /**
     * @brief 创建出来的请求句柄
     */
    OH_QoS_GewuRequest request;

    /**
     * @brief 错误码。
     *
     *         - 请求提交成功返回OH_QOS_GEWU_OK。
     *
     *         - 由于没有足够的内存而创建会话失败返回OH_QOS_GEWU_NOMEM。
     */
    OH_QoS_GewuErrorCode error;
} OH_QoS_GewuSubmitRequestResult;


/**
 * @brief 用于接收回复的回调。
 *
 * @param context 提交请求时指定的用户上下文句柄。
 *
 * @param reponse 回复的json字符串，包含以下参数：
 *
 *        - message: 包含下列字段的消息。
 *
 *            - role: string. 消息的角色类型，应为"assistant".
 *
 *            - content: string。消息内容。
 *
 *        - finish_reason: string or null. 停止原因，可能的值如下：
 *
 *            - null: 表示没有停止。流式推理中会有多次回复，只有最后一次回复有非空的"finish_reason"。而非流式推理只有一次回复，且"finish_reason"非空。
 *
 *            - "stop": 正常停止。
 *
 *            - "abort": 用户主动提前中止。
 *
 *            - "length": token数超过限制。
 *
 * @since 20
 */
typedef void (*OH_QoS_GewuOnResponse)(void* context, const char* response);

/**
 * @brief 创建格物会话。
 *
 * 会话对象的声明周期从CreateSession函数返回开始，到调用DestroySession为止。
 *
 * 会话属性的json字符串。
 *
 * 该json字符串支持以下字段：
 *
 *     - model: string. 表示会话使用的模型的路径。
 *
 * `attributes` json字符串例子：
 *
 * @code{.json}
 * {
 *
 *     "model": "/data/storage/el2/base/files/qwen2/"
 *
 * }
 * @endcode
 *
 * @param attributes 会话attributes的json字符串。
 *
 * @return 创建会话的结果。
 *
 * @since 20
 */
OH_QoS_GewuCreateSessionResult OH_QoS_GewuCreateSession(const char* attributes);

/**
 * @brief 销毁格物会话。
 *
 * 建议用户应当等待至所有请求都已完成或中止，然后再调用该接口来销毁会话。如果调用该接口时还有正在进行的请求，那些请求将会被中止，且用户不会再收到回复。注意，在调用完该接口后，会话对象无法再被使用。
 *
 *
 * @param session 要销毁的会话的句柄。
 *
 * @return 错误码
 *
 *         - 会话销毁成功，返回值为`OH_QOS_GEWU_OK`。
 *
 *         - 找不到会话返回OH_QOS_GEWU_NOENT。
 *
 * @since 20
 */
OH_QoS_GewuErrorCode OH_QoS_GewuDestroySession(OH_QoS_GewuSession session);

/**
 * @brief 停止指定的请求。
 *
 * 成功调用该函数后，client不会再收到该请求的回复，且该请求句柄无法再被使用。
 *
 * @param session 请求提交到的会话句柄。
 *
 * @param request 请求的句柄。
 *
 * @return 错误码。
 *
 *         - 成功停止请求返回OH_QOS_GEWU_OK。
 *
 *         - 找不到请求返回OH_QOS_GEWU_NOENT。
 *
 * @since 20
 */
OH_QoS_GewuErrorCode OH_QoS_GewuAbortRequest(OH_QoS_GewuSession session, OH_QoS_GewuRequest request);

/**
 * @brief 提交请求。
 *
 * 请求的json字符串，支持以下字段：
 *
 *     - messages: array. 表示消息的数组其中每个元素支持以下字段：
 *
 *         - role: string. 消息的角色类型。
 *
 *             - "developer": 开发者或系统提供的指示。
 *
 *             - "user":用户输入。
 *
 *             - "assistant": 模型生成结果。
 *
 *         - content: string. 消息内容。
 *
 *     - stream: boolean or null; 可选。是否使能流式推理，默认为非流式。
 *
 * json字符串例子：
 *
 * @code{.json}
 * {
 *
 *      "messages": [
 *
 *          {
 *
 *              "role": "developer",
 *
 *              "content": "Your are a helpful assistant."
 *
 *          },
 *
 *          {
 *
 *              "role": "user",
 *
 *              "content": "What is OpenHarmony"
 *
 *          }
 *
 *      ],
 *
 *      "stream": true
 *
 * }
 *
 * @endcode
 *
 * @param session 会话句柄，表示请求要提交到哪个会话。
 *
 * @param request 请求的json字符串。
 *
 * @param callback 接受回复的回调。
 *
 * @param context 要传给回调的用户上下文指针。
 *
 * @return 格物提交请求结果。
 *
 *         - 提交请求成功，返回值`OH_QoS_GewuSubmitRequestResult`里的`error`为`OH_QOS_GEWU_OK`，`request`为请求句柄。
 *
 *         - 提交请求失败，返回值`OH_QoS_GewuSubmitRequestResult`里的`error`为错误原因，其中`OH_QOS_GEWU_NOMEM`表示没有足够的内存处理该请求。
 *
 * @since 20
 */
OH_QoS_GewuSubmitRequestResult OH_QoS_GewuSubmitRequest(OH_QoS_GewuSession session, const char* request,
    OH_QoS_GewuOnResponse callback, void* context);

#ifdef __cplusplus
}
#endif
/** @} */
#endif // QOS_H